Skip to content

feat(gamepad_map): GamepadMapService + Gamepad Map Console web app - #919

Open
finger563 wants to merge 7 commits into
mainfrom
feat/gamepad-map-service
Open

finger563 wants to merge 7 commits into
mainfrom
feat/gamepad-map-service

Conversation

@finger563

Copy link
Copy Markdown
Contributor

Description

Stacked on #918 (base feat/gamepad-map). Retarget it to main once #918 merges.

This adds a device-side service and a hosted web console, so a user can edit gamepad maps in the browser and watch a controller's input before and after mapping, live.

espp::GamepadMapService

It uses dispatcher module 11 and protocol espp.gamepad_map v1. The wire spec and a host-buildable codec are in include/detail/gamepad_map_protocol.hpp.

Requests and what they do:

Request Effect
GET_INFO Returns limits, the connected controller (VID:PID + name) and whether it has a profile
GET_MAP Returns the default map or a per-controller profile. The reply says whether that profile exists (a missing one answers with the default map its controller uses today)
SET_MAP Validates the map with GamepadMap::valid(), then saves it through GamepadProfiles
ERASE_PROFILE / RESET_ALL Remove one profile / every profile; saved
LIST_PROFILES Lists the stored profiles
SET_STREAM Starts INPUT events carrying the raw and mapped state every period

Protocol behaviour:

  • The device ends the INPUT stream itself when the host stops renewing its lease (Config::stream_lease), so a closed tab does not leave it streaming.
  • While streaming, a controller change is pushed as an unsolicited INFO.
  • Host decoders ignore appended fields of device-to-host messages, so v1 can grow compatibly. Requests stay strict.

Application side:

  • set_controller() / clear_controller(). set_controller() returns the map to apply.
  • publish_input(raw, mapped) is a single atomic load while nobody is streaming.
  • Config::on_active_map_changed fires when a host's change gives the connected controller a new map.

GamepadMapRule::valid() also now rejects two rules that could never do anything: a negative threshold on a trigger, and KEEP_SOURCE with no target.

web/gamepad_map_console.html

  • Live view: raw and mapped input side by side as a button grid, stick pads and axis bars.
  • Map picker: the default map, the connected controller's profile (created on save), stored profiles, or a new VID:PID / name.
  • Rule editor:
    • kind, source, target (or "none"), keep source, and the kind's parameter
    • a one-line description per rule
    • learn-by-pressing
    • presets matching the C++ builder helpers
    • per-stick dead zones
  • Validation and saving: local validation mirrors valid(). Save, revert, erase and reset use inline confirms (no blocking dialogs).
  • Shared code: the discovery, connection, navigation and hand-back blocks are byte-identical to the other consoles.

webapp_example

  • Runs on esp32s3 / esp32p4 over USB vendor (WebUSB) + CDC (Web Serial).
  • Serves the standard system / monitor / OTA / core dump services.
  • Keeps the profiles on a 128 KB LittleFS partition.
  • A demo controller supplies the input: circling sticks, ramping triggers, cycling buttons, and the BOOT button as South for trying learn.

Tests, docs, CI

  • Tests:
    • gamepad_map_protocol_host_test.cpp checks golden encodings and decoding leniency.
    • web/test/gamepad_map_codec_test.js (node) tests the console's copy of the codec, the validation, the presets and the learn logic.
    • Both run in gamepad_map_tests.yml.
  • Console tests:
    • The console is added to the dispatcher web tests' console list.
    • apps_registry_test's undeclared-protocol check now also matches protocol ids containing _ (it silently skipped them before).
  • Docs:
    • module 11 in the dispatcher module tables, plus the missing module 10 row in the README table
    • web_apps.rst
    • gamepad_map.rst and an example page
    • Doxyfile
  • CI: a build entry for the example (IDF_COMPONENT_MANAGER=0).

Motivation and Context

Users need to configure per-controller button / axis mapping from a web page, both on the BLE -> USB controller bridge and in emulators. This is the reusable service and console that any espp USB / serial device can register.

How has this been tested?

  • Host tests with g++ 16, -std=c++23 -Wall -Wextra -Werror:
    • gamepad_map_protocol_host_test
    • gamepad_map_host_test (with the new validation rules)
  • Node tests:
    • gamepad_map_codec_test.js
    • resolve_module_id_test.js (11 consoles)
    • apps_registry_test.js (19 apps)
  • webapp_example builds for esp32s3 with IDF_COMPONENT_MANAGER=0 and no warnings.
  • cppcheck with the CI flags is clean on the component.
  • The console loads without script errors in headless Chrome, with and without ?autoconnect=1. A scripted fake device exercised it as well: connect, load / save / erase / reset, presets, validation, learn, lease renewal and an unsolicited INFO.
  • Not tested on hardware yet.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation Update
  • Hardware (schematic, board, system design) change
  • Software change

Checklist:

  • My change requires a change to the documentation.
  • I have added tests to cover my changes.
  • I have updated the documentation accordingly.
  • I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build github action.
  • All new and existing tests passed.
  • My code follows the code style of this project.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU

finger563 and others added 3 commits November 21, 2026 15:25
…r profiles; hid-rp decoder for BLE HID gamepads

hid-rp (hid-rp-report-map.hpp, GamepadDecoder):
- Layout::Android (1 south, 2 east, 4 west, 5 north, 7/8 L1/R1, 9/10 L2/R2,
  11 select, 12 start, 13 home, 14/15 L3/R3), picked when the descriptor
  reports Simulation-page Brake / Accelerator triggers: BLE HID gamepads,
  the Xbox Wireless controller over BLE, espp's own gamepad report.
- Analog triggers (GamepadReport::lt / rt) from Brake / Accelerator, or
  Rx / Ry when Z / Rz are the right stick (DualShock); Rx no longer
  overwrites the right stick's X on such pads. Capture (consumer Record)
  is reported on its own (GamepadReport::capture).
- decode(report_id, payload) for transports that carry the report ID out of
  band (BLE), and a stateful update() / reset() that decodes the latest
  report of every ID together, so a pad that splits its state over several
  reports does not reset half of it on every report.
- set_combine_controls(false) turns off the emulator conveniences (left
  stick as d-pad, analog triggers as L2/R2, Capture as Home) for a
  pass-through; on by default, so existing users see no change.
- Per-field roles are worked out once in the constructor; layout_name().

gamepad_map (new component):
- GamepadState: buttons by position (south / east / west / north ...),
  sticks -32767..32767 (Y down) and triggers 0..32767.
- GamepadMapRule / GamepadMap: radial stick dead zones plus button ->
  button, axis -> button (threshold), button -> axis (value) and axis ->
  axis (scale / invert) rules; sources are moved unless KEEP_SOURCE,
  unmapped controls pass through, apply() does not allocate. Presets for
  swaps, inversion, stick <-> d-pad and triggers <-> buttons; valid().
- GamepadProfiles: a default map plus one map per controller type
  (vendor / product ID, name when both are 0), validated and saved
  atomically with PersistentData.
- to_gamepad_state() from hid_rp::GamepadReport, fmt formatter, example
  (esp32s3, LittleFS), docs, host test; CI workflow gamepad_map_tests.yml
  also runs the hid-rp report-map host test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
…eference, parameters no longer shadow pressed() / profile())

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
- GamepadMapService (dispatcher module 11, protocol espp.gamepad_map v1,
  wire spec + host-buildable codec in include/detail/gamepad_map_protocol.hpp):
  GET_INFO (limits, connected controller, whether it has a profile),
  GET_MAP / SET_MAP (default map or a per-controller profile; validated,
  saved through GamepadProfiles), ERASE_PROFILE, LIST_PROFILES, RESET_ALL,
  and SET_STREAM: INPUT events (raw + mapped state) every period, ended by
  the device when the host stops renewing the lease, plus an unsolicited
  INFO when the controller changes while streaming. MAP says whether the
  requested profile exists. Host decoders ignore appended fields of
  device -> host messages, so the protocol can grow.
- Application side: set_controller() / clear_controller() (returns the map
  to apply), publish_input() (an atomic load while nobody streams),
  Config::on_active_map_changed when a host changes the connected
  controller's map.
- GamepadMapRule::valid() also rejects a negative threshold on a trigger
  and KEEP_SOURCE with no target (rules that could never do anything).
- web/gamepad_map_console.html: live raw / mapped input (button grid,
  stick pads, axis bars), map picker (default / connected controller /
  stored profiles / new), rule editor with per-kind parameters, learn by
  pressing, presets, dead zones, local validation, save / revert / erase /
  reset with inline confirms; shared discovery / connection / navigation /
  hand-back blocks byte-identical to the other consoles.
- webapp_example (esp32s3 / esp32p4, USB vendor + CDC, the standard
  system / monitor / OTA / core dump services, profiles on LittleFS, a demo
  controller with the BOOT button as South).
- Tests: gamepad_map_protocol_host_test.cpp (golden encodings), the web
  codec test (node), both in gamepad_map_tests.yml; the console is in the
  dispatcher web tests' console list; apps_registry_test's undeclared-
  protocol check now matches protocol ids with '_'.
- Docs: module 11 in the dispatcher module tables (and the missing module
  10 row in the README), web_apps.rst, gamepad_map.rst + example page,
  Doxyfile; CI build entry for the example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
finger563 and others added 3 commits November 21, 2026 18:55
gamepad_map:
- Radial dead zone no longer caps the stick's magnitude: a square-gate
  corner (both axes full) stays a full diagonal instead of ~23170 per axis.
- A trigger inverted onto a trigger reads from full (32767 - v) instead of
  clamping to "never pressed".
- Documented that a map's rules apply in parallel to the controller's
  input (a source used twice feeds both targets).
- GamepadProfiles: names stored cut to 64 bytes (and matched cut); the
  PersistentData size limit is derived from max_profiles so whatever save()
  writes, load() accepts; a file that cannot be read is set aside as
  <file>.unreadable (load_error()) instead of being overwritten by the next
  change; stored maps are sanitized rule by rule (an invalid rule no longer
  drops its whole profile), unmatchable profiles (no VID, PID or name) are
  dropped; has_profile() / profile_count(); one in-memory copy of the store.
- Example / README: check the parsed report map before using it; the
  example's expected output matches what it prints.

hid-rp GamepadDecoder:
- Button 13 is Home on the Xbox-style and DirectInput layouts (the PS
  button of a DualShock / DualSense).
- update() returns false (and leaves `out` alone) for a report with no
  gamepad control (e.g. the Xbox battery report) instead of re-sending the
  last state.
- Each field's report slot is computed once (no per-field search per report).

Tests for all of the above; the documented host-test commands work pasted
into a shell again (line continuations + -Wno-comment); the host test
workflow also runs on logger / format / base_component changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
# Conflicts:
#	.github/workflows/gamepad_map_tests.yml
- set_controller() / clear_controller() never send: a controller change
  flags an INFO that the stream task sends, so they are safe on a radio /
  host task (they used to do blocking transport I/O on the caller).
- publish_input() always keeps the latest state (a 32-byte copy under a
  lock), and a controller change resets it, so a stream that starts later or
  a new controller never shows stale input.
- INPUT's changed flag is only forced when the stream (re)starts, not on
  every lease renewal; INFO is also sent when a stream starts.
- The lease expiry is decided under the service mutex (where renewals take
  it), so a renewal is never undone; an expired stream ends its task (no idle
  wake-ups for the rest of the uptime) and the next SET_STREAM starts a new
  one; the period is clamped to Config::max_stream_period (1 s).
- GET_INFO / LIST_PROFILES / RESET_ALL reject a payload (a newer protocol's
  request is never acted on as a v1 one).
- Changes and the notifications they cause are serialized on the store's
  new GamepadProfiles::change_mutex(), so services sharing a store notify in
  order and the last notification carries the stored map.
- INFO uses GamepadProfiles::profile_count() / has_profile() (no copies).
- Example: one TX mutex per transport, and a frame that does not fit the TX
  FIFO is dropped instead of blocking the sender; the demo input stays below
  the console's 50% learn threshold so learn picks the BOOT button; BOOT is
  GPIO 35 on the ESP32-P4; README snippet takes the map mutex.
- Protocol: Reader::ok() (unused) removed; doc updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
Base automatically changed from feat/gamepad-map to main November 22, 2026 14:30
# Conflicts:
#	.github/workflows/build.yml
#	.github/workflows/gamepad_map_tests.yml
#	components/gamepad_map/CMakeLists.txt
#	components/gamepad_map/README.md
#	components/gamepad_map/idf_component.yml
#	components/gamepad_map/include/gamepad_map.hpp
#	components/gamepad_map/include/gamepad_profiles.hpp
#	components/gamepad_map/test/gamepad_map_host_test.cpp
#	doc/Doxyfile
#	doc/en/input/gamepad_map.rst
@github-actions

Copy link
Copy Markdown

✅Static analysis result - no issues found! ✅

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant